Xml4ipl versão 1.1

Copiright 2009 Iplenix Serviços de Internet LTDA - sobre a versão 3 da licença GNU Lesser General Public License

 

O xml4ipl é um protocolo leve de comunicação entre máquinas e programas de computador dedicado a possibilitar aplicações simples de m2m (machine to machine communication).

Ele foi desenvolvido pensando em prover uma forma simples e leve para que equipamentos eletrônicos e programas de computador que geram ou coletam dados possam transmitir estes para um local na Internet de onde podem ser acessados.

Os tipos de dados que podem ser enviados usando o xml4ipl são abrangentes. É possível enviar dados numéricos como leituras de sensores de temperatura, ou uso de processador de um computador, ou o número de vendas registradas em um ponto de venda. É possível também enviar dados complexos como imagens e vídeos gravados por uma câmera na Internet, além de status do equipamento e de seus sensores, e algumas configurações locais.

Esta especificação descreve o formato como os dados devem trafegar pela rede. Descreve algumas possíveis formas de transporte dos dados usando o protocolo HTTP. Descreve formas de autenticação dos equipamentos. E descreve formas de segurança na transmissão dos dados pelo uso do protocolo HTTPS. Outras formas de transporte, autenticação e segurança no tráfego dos dados podem ser adicionadas a especificação desde que mantido o seu conteúdo.


Conteúdo

[esconder]

O protocolo

As partes do protocolo de envio

  • "header http" - Este "header http" está presente porque a camada de transporte disponível para a comunicação é o http e https. Deve ser observado no "header http" o valor do campo "Content-Length" que tem que estar correto. A contagem de bytes informada neste campo se inicia logo após o final do "header http".
  • autenticação do equipamento - deve ser enviado o "logname" e o "password" do equipamento (dispositivo remoto) ou do conjunto de definição de dispositivos remotos (RCP) para que a comunicação seja aceita.

É recomendado o uso do HTTPS (http seguro) como camada de transportes para evitar que a senha possa ser interceptada na rede.

  • login
  • password

Exemplo

O que transita pela linha. Envio a partir do equipamento remoto 

POST /xml4ipl.fcgi HTTP/1.0
User-Agent: Wget/1.10.2 (Red Hat modified)
Accept: */*
Host: demo.webmetrix.com.br:12000
Content-Type: application/x-www-form-urlencoded
Content-Length: 832

login:perfil.01.6142.6103
password:webmetrix 
<xml4ipl ver="1.1" device="teste_m2m_generico">
  <Sensor name="Vento" timestamp="20081107144436"  status="OK" unit="Km/h">3636</Sensor>
  <Sensor name="Vento2" timestamp="20081107144436" status="OK" unit="Km/h">4436</Sensor>
  <Sensor name="Vento3" timestamp="20081107144436" status="OK" unit="Km/h">3644</Sensor>
  <Sensor name="Vento4" timestamp="20081107144436" status="OK" unit="Km/h">1436</Sensor>
  <Sensor name="Vento5" timestamp="20081107144436" status="OK" unit="Km/h">3614</Sensor>
  <Sensor name="Vento6" timestamp="20081107144436" status="OK" unit="Km/h">3607</Sensor>
  <Sensor name="Vento7" timestamp="20081107144436" status="OK" unit="Km/h">0736</Sensor>
  <Sensor name="Temperatura" timestamp="20081107144436" status="OK" value="36" unit="C"/>
</xml4ipl>

As partes do protocolo de resposta

  • "header http" - Este "header http" está presente porque a camada de transporte disponível para a comunicação é o http e https. Na resposta deve ser observado o código de resposta do protocolo HTTP que fica na primeira linha logo após o "HTTP/1.1", e que no caso deste exemplo está como "200 OK" significando que a requisição HTTP foi atendida. Outros códigos de erro do protocolo HTTP determinam que a requisição nem chegou ao tratador do xml4ipl.
As seguintes url's oferecem mais informações a respeitos dos códigos de erro do protocolo HTTP:
É importante salientar que mesmo tendo sido bem sucedia a requisição HTTP pode ter ocorrido erro no tratamento do xml4ipl

Resposta da plataforma para o equipamento remoto 

HTTP/1.1 200 OK
Date: Fri, 07 Nov 2008 16:55:12 GMT
Server: Apache/2.2.3 (CentOS)
Content-Length: 90
Connection: close
Content-Type: text/xml 

<xml4ipl ver="1.1" device="teste_m2m_generico">
  <Response resultCode="0" message="OK"/>
</xml4ipl>

xml4ipl v1.1

Tag principal do protocolo.

Atributos

Obrigatórios

  • ver - versão do protocolo usada nesta comunicação

Casuísticos

  • device - identificador do equipamento (dispositivo remoto) que está enviando a comunicação. Este atributo só é opcional e será ignorado nos casos de encapsulamento de protocolos em que o identificador do equipamento estiver sendo enviado dentro do pacote de dados dentro da tag Packet. Em qualquer outro caso este atributo é obrigatório.

Opcionais

  • timestamp ou localtimestamp - tempo em segundos informado pelo dispositivo remoto,
nos processos realizados pelos dispositivo remoto são identificados claramente três diferentes momentos, são estes:
  1. O tempo em que o dispositivo remoto coletou dados dos sensores,
  2. o tempo que o dispositivo remoto coletou seus parâmetros e/ou calculou seu "status",
  3. e o tempo em que o dispositivo remoto iniciou a comunicação com a plataforma.
Este atributo timestamp ou localtimestamp se refere ao momento descrito no segundo item.
  • Se for usado timestamp significa que o tempo está informado no fuso horário UTC,
  • e se for usado o localtimestamp indica hora local no fuso da remota.
Veja o formato de envio dos valores de tempo.

Sub-tags

Sub-tags de envio

Sub-tags especiais

  • Packet - usada para encapsular outros protocolos de transmissão de dados em um envelope xml4ipl
  • RawData - usada para o envio de dados brutos, dados que a plataforma não conhece o formato e apenas irá armazenar sem qualquer crítica

Sub-tags de resposta

  • Response - informa o resultado do envio
  • Error - informa situações de erro
  • Warning - informa situações de warning

Possíveis combinações das sub-tags

As combinações possíveis de tag's são restritas. Nem todas podem aparecer com todas.

  • Nenhuma outra tag pode vir junto com a tag Response

Exemplo:

Envio 

<xml4ipl ver="1.1" device="server10" status="OK" timestamp="20080826145756" sender_agent="novus-superview-v2.00" >
    <Property name="location" value="30.434343,55.343443,30" />
    <Property name="communication_frequency" value="15" />

    <Record timestamp="20080826145756">
        <Sensor name="sensor01" dataType="string" timestamp="20080826143512" value="processos"/>
        <Sensor name="sensor02" dataType="analog" timestamp="20080826143115" 
                      status="WARNING" unit="%" value="92"/>

        <SensorProperties name="sensor02">
            <StatusProperties>
                <PropertyRange name="range_ok" gt="0" lt="100"/>
                <PropertyRange name="range_warning" ge="80" lt="95"/>
                <PropertyRange name="range_critical" ge="95" gt="100"/>
            </StatusProperties>
        </SensorProperties>
    </Record>
</xml4ipl>

Resposta 

<xml4ipl ver="1.1" device="server10">
  <Response resultCode="0" message="OK"/>
</xml4ipl>

Response

Tag que informa a resposta da comunicação

Atributos

  • resultCode - número que indica o resultado da comunicação
  • message - mensagem de texto relativa ao resultCode

Valores possíveis

resultCode message
0 OK
-1 Authentication failed
-2 Syntax error
-3 Internal temporary error (try later)

Exemplo

<xml4ipl ver="1.1" device="server10">
  <Response resultCode="0" message="OK"/>
</xml4ipl>

Sensor

Tag que informa uma leitura realizada do valor de um sensor que é a menor unidade de leitura de dados do dispositivo remoto. O valor lido representa alguma grandeza como graus celsius, percentagem, etc. O atributo "unit" possibilita informar a unidade na qual o valor lido está representado. O dispositivo remoto pode ter os seus próprios critérios para avaliar a condição, o "status" do seu sensor, e limites considerados normais para os valores lidos. O atributo de "status" está disponível para informar esta condição.

Atributos

Obrigatórios

  • name - informa a identificação inequívoca do sensor dentro do dispositivo remoto. Cada sensor tem que ter um nome diferente dentro do dispositivo remoto. É composto por uma seqüência de caracteres alfanúmericos

Casuísticos

  • value - valor coletado que está sendo enviado. Este atributo só é opcional e será ignorado nos casos de ter status definido. Já que uma remota pode comunicar o valor ou o status de um sensor. Em qualquer outro caso este atributo é obrigatório.
  • status - calculado pela remota. Os valores possíveis estão informados em #Formato de envio dos valores de "status". Este atributo é obrigatório somente na ausência do atributo value. Em qualquer outro caso este atributo é opcional.

Opcionais

  • dataType - informa o tipo de dado que foi lido pelo sensor, e se não for informado é tratado como "analog"
Pode assumir os seguintes valores:
  • analog - representa valores em ponto flutuante ou IEEE754 (ascii hexa seguidos de %f)
  • digital - O tipo digital aceita os valores 0 ou 1
  • string - O tipo string, permite qualquer seqüência de caracteres válidos dentro de um XML.
  • timestamp ou localtimestamp - carimbo de tempo que indica o momento da coleta do dado deste sensor que está sendo enviado nesta tag. No caso deste atributo não ser informado será usado o que for informado na tag Record, ou na tag xml4ipl. E se faltarem todos estes será considerado o momento em que a plataforma recebeu a comunicação do dispositivo remoto.
  • unit - Especifica a unidade na qual o valor é informado e deve ser escrito sob a forma de uma string alfanumérica onde podem aparecer espaços.

Futuras implementações

  • Tipo de dado location - O tipo location aceita valores de latitude, longitude e altitude
  • Tipo de dado "raw_data". Onde poderá ser enviado como dado de um sensor um bloco de dados qualquer.
No atributo dataType deverá ser colocado o valor raw_data
Juntamente com o (dataType="raw_data") é possível usar outros dois atributos que são:
  • encoding - especifica o tipo de codificação utilizada (atualmente suporta-se base64)
  • content_type - indica o tipo de dado que está contido para uso de quem for ler estes dados. A plataforma não fará qualquer crítica a este atributo e dado
Neste caso o atributo value não poderá ser representado como atributo e sim colocado dentro do elemento "Sensor".
Exemplo: <Sensor ... ><![CDATA[valor comunicado]]></Sensor>

Exemplos

        <Sensor name="sensor01" unit="%" dataType="analog" timestamp="20080826143512" 
                                            value="12.4" status="OK"/>

        <Sensor name="sensor01" unit="%" dataType="analog" timestamp="20080826143512"
                                            value="12.4"/>

        <Sensor name="sensor01" dataType="analog" timestamp="20080826143512" value="12.4"/>

        <Sensor name="sensor01" timestamp="20080826143512" value="12.4"/>

        <Sensor name="sensor01" value="12.4"/>

        <Sensor name="sensor02" dataType="string" timestamp="20080826143512" 
                                            value="processos"/>

        <Sensor name="sensor01" dataType="string" value="processos" status="CRITICAL"/>

        <Sensor name="sensor03" dataType="location" value="30.434343,55.343443,30"/>

        <Sensor name="sensor03" dataType="location" timestamp="20080826143512" 
                                            value="30.434343,55.343443,30"/>

Record

Tag específica para o agrupamento de leituras de sensores. Ela deve ser usada para definir um conjunto de leituras de diferentes sensores. As leituras podem ter sido feitas em um mesmo momento, e sendo assim a tag Record terá um atributo de timestamp ou localtimestamp dispensando este atributo das sub-tags Sensor. O Record também pode ser usado simplesmente para agrupar as leituras para posterior recuperação nos relatórios, mostrando os valores lidos pelos sensores que foram informados dentro do Record. É importante que dentro de uma tag Record venha apenas uma leitura para cada sensor, ou seja que não exista duas tag Sensor com o mesmo atributo "name".

A tag Record pode também conter sub-tags SensorProperties. Esta forma deve ser usada para informar o momento da alteração das propriedades. Devem ser usadas várias tags Record com sub-tags SensorProperties para informar sucessivas alterações sobre as mesma propriedades que ocorram entre comunicações do dispositivo remoto com a plataforma.

Atributos

Opcionais

  • timestamp ou localtimestamp - informa o momento de leitura dos valores dos sensores, ou da alteração das propriedades de sensores que estão sendo informadas nas sub-tags. No caso em que a tag contenha apenas sub-tag's Sensor que contenham os seus próprios atributos timestamp ou localtimestamp, este atributo não é necessário não é necessário na tag Record.

Sub-tags

Exemplos

Sensores sem marcação de tempo. Herdam o tempo informado pelo "Record" 

    <Record timestamp="20080826145756">
        <Sensor name="sensor01" dataType="string" value="processos"/>
        <Sensor name="sensor02" dataType="analog" status="WARNING" unit="%" value="92"/>
    </Record>

Sensores com marcação de tempo. Sem a necessidade do atributo de tempo no "Record" 

    <Record>
        <Sensor name="sensor01" dataType="string" timestamp="20080826143512" value="processos"/>
        <Sensor name="sensor02" dataType="analog" timestamp="20080826143115" 
                      status="WARNING" unit="%" value="92"/>
    </Record>

Obrigatório o uso do atributo "timestamp" quando só contiver "SensorProperties".

Envia os parâmetros do sensor "sensor02" e informa a alteração de alguns deles na mesma mensagem. 

    <Record timestamp="20080826145756">
        <SensorProperties name="sensor02">
            <PropertyRange name="range_ok" ge="0" le="100"/>
            <PropertyRange name="range_warning" gt="80" le="95"/>
            <PropertyRange name="range_critical" gt="95" le="100"/>
        </SensorProperties>
    </Record>
    <Record timestamp="200808261550">
        <SensorProperties name="sensor02">
            <PropertyRange name="range_warning" ge="80" lt="99"/>
            <PropertyRange name="range_critical" ge="99" le="100"/>
        </SensorProperties>
    </Record>

A marcação de tempo do "Record" é usada pela "SensorProperties" enquanto os sensores possuem suas próprias marcações de tempo. 

    <Record timestamp="20080826145756">
        <Sensor name="sensor01" dataType="string" timestamp="20080826143512" value="processos"/>
        <Sensor name="sensor02" dataType="analog" timestamp="20080826143115" 
                      status="WARNING" unit="%" value="92"/>

        <SensorProperties name="sensor02">
            <PropertyRange name="range_ok" ge="0" le="100"/>
            <PropertyRange name="range_warning" gt="80" le="95"/>
            <PropertyRange name="range_critical" gt="95" le="100"/>
        </SensorProperties>
    </Record>

SensorProperties

É usada para informar dados de configuração de sensores. A tag informa o sensor para o qual serão configuradas propriedades e contém sub-tags com as propriedades.

Atributos

Obrigatórios

  • name - com o nome do sensor dentro da remota

Sub-tags

Possíveis configurações

A lista com as possíveis configurações pode ser encontrada em #Parâmetros de configuração de dispositivos e sensores

Exemplos

        <SensorProperties name="sensor02">
            <StatusProperties>
               <PropertyRange name="range_warning" gt="80" le="95"/>
               <PropertyRange name="range_critical" gt="95" lt="100"/>
               <PropertyRange name="range_normal" any="true"/>
            </StatusProperties>
            <Property name="propriedade" value="142"/>
        </SensorProperties>

StatusProperties

É usada para informar intervalos de configuração de status. A ordem em que os intervalos são descritos informa a ordem que serão avaliados no momento de cálculo do status.

Atributos

Sub-tags

Exemplos

            <StatusProperties>
               <PropertyRange name="range_warning" gt="80" le="95"/>
               <PropertyRange name="range_critical" gt="95" lt="100"/>
               <PropertyRange name="range_normal" any="true"/>
            </StatusProperties>

Property

Tag que informa configurações do dispositivo remoto ou do sensor.

Pode estar dentro da tag xml4ipl ou da tag SensorProperties.

Atributos

Obrigatórios

  • name - nome do atributo para o qual se está informando o valor.
  • value - valor informado.

Possíveis configurações

A lista com as possíveis configurações para dispositivos remotos e sensores pode ser encontrada em #Parâmetros de configuração de dispositivos e sensores.

Exemplos

    <Property name="location" value="30.434343,55.343443,30" />
    <Property name="communication_frequency" value="15" />

PropertyRange

Tag que informa configurações de um dispositivo remoto ou sensor.

Pode estar dentro da tag xml4ipl ou da tag SensorProperties.

Atributos

Obrigatórios

  • name - nome do atributo para o qual se está informando o valor.

Opcionais

  • ge - valor mínimo para o limite, o valor especificado é aceito dentro do limite
  • gt - valor mínimo para o limite, o intervalo começa imediatamente acima do valor especificado
  • le - valor máximo para o limite, o valor especificado é aceito dentro do limite
  • lt - valor máximo para o limite, o intervalo começa imediatamente abaixo do valor especificado
  • any=true - intervalo abrange todos os valores existentes

Possíveis combinações das sub-tags

Os atributos de mínimo ge e gt são alternativos entre si, ou se usa um ou ou outro.

Os atributos de máximo le e lt também são alternativos entre si.

O atributo any deve vir sozinho, não podendo ser misturado com atributos de mínimo e de máximo.

A ausência de atributos any, de mínimo e de máximo significa apagar o range do nome especificado.

Especificando-se um valor mínimo sem especificar um valor máximo, significa intervalo não limitado acima, qualquer valor acima do valor de mínimo especificado é aceito. Especificando-se um valor máximo sem especificar um valor mínimo, significa intervalo não limitado abaixo, qualquer valor abaixo do valor de máximo especificado é aceito.

Possíveis configurações

A lista com as possíveis configurações para dispositivos remotos e sensores pode ser encontrada em #Parâmetros de configuração de dispositivos e sensores

Exemplos

    <PropertyRange name="range_ok" ge="0" le="100"/>
    <PropertyRange name="range_warning" gt="80" le="95"/>
    <PropertyRange name="range_critical" gt="95" le="100"/>

RawData

Tag para o recebimento de dados em formato desconhecido. Deve ser usada quando o dispositivo remoto enviar dados a serem armazenados na plataforma sem que seja feita qualquer crítica. Por exemplo um câmera de fotos na Internet que só envie fotos, ou um coletor de dados que deposite dados encriptados que não podem ser abertos pela plataforma.


Somente as tag's "Property" e "PropertyRage" podem vir junto com a "RawData" permitindo que o dispositivo remoto transmita suas configurações


Atributos

Opcionais

  • encoding - especifica o tipo de codificação utilizada para os dados. Pode ser qualquer uma pois não será feita qualquer crítica pela plataforma
  • dataformat - especifica o tipo de codificação utilizada para os dados binários, a plataforma conhece alguns formatos para realizar "digestão" dos dados e processar automaticamente os dados binários para recepção.
  • content_type - indica o tipo de dado que está contido para uso de quem for ler estes dados. A plataforma não fará qualquer crítica a este atributo e dado
  • filename - indica um nome de arquivo com extensão a ser utilizado em uma futura recuperação deste dados da plataforma. A plataforma não fará qualquer crítica a este atributo.
  • note - qualquer texto enviado pelo dispositivo remoto que será armazenado junto com o bloco de dados

Exemplo

<xml4ipl ver="1.1" device="camera01" timestamp="20080826145756" sender_agent="linksys-icam3000" >
    <Property name="location" value="30.434343,55.343443,30" />

    <RawData encoding="64" content_type="gif" note="imagem frente casa"><![CDATA[
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
        ]]></RawData>
</xml4ipl>

<xml4ipl ver="1.1" device="camera01" timestamp="20080826145756" sender_agent="linksys-icam3000" >
    <RawData><![CDATA[
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
          #VDFFASDFFVASDFASDFJLKASDFJLAKSDJFOLIJQPOWIEJFAOIU0Q945RKAJSDFLKJM
        ]]></RawData>
</xml4ipl>

Packet

Tag usada para encapsular outros formatos de envio de dados de sensores dentro de uma comunicação usando o protocolo "xml4ipl". Quando um pacote deste for recebido a plataforma vai abrir e tratar campo a campo de forma a alimentar todos os atributos dos sensores e do dispositivo remoto. É fundamental que o "dataformat" e o "encoding" sejam conhecidos para que os dados possam ser processados.


Somente as tag's "Property" e "PropertyRange" podem vir junto com a "Packet" permitindo que o dispositivo remoto transmita suas configurações

Somente 1 (uma) tag "Packet" pode vir por comunicação.

Atributos

Obrigatórios

  • dataformat - especifica em qual formato de dados os dados contidos neste sensor são especificados.

Opcionais

  • encoding - especifica o tipo de codificação utilizada (atualmente suporta-se base64). Tem que ser uma codificação conhecida pela plataforma pois estes dados serão tratados por ela

Exemplos

<xml4ipl ver="1.1" device="server_nsca" timestamp="20080826145756" status="OK" sender_agent="iplenix-send_nsca-v1.0" >
    <Property name="location" value="30.434343,55.343443,30" />

    <Packet dataformat="nagios"><![CDATA[
myhost   0   OK
myhost   LoadAverage             0       OK - load=0.26|load1=0.160;5.000;10.000;0;
myhost   CPU Load                2       CRITICAL - use 100.00% idle : swap 10 % | 'CPU Usage'=100.00%;85;90
myhost   Used Memory             0       OK - 159 MB (33%) Used Memory | 'used memory'=33%;75;90;
myhost   Traffic eth0            0       OK - 0.006 Kbytes/s | 'Traffic'=0.006KB;5000;7500
myhost   Space on /              0       DISK OK - free space: / 27553 MB (80% inode=96%);| /=6811MB;28963;32583;0;36204
        ]]></Packet>
</xml4ipl>

Error

Tag usada para listar erros encontrados no XML4IPL recebido. Esta tag só é retornada pelas Urls de depuração. E indica situações onde o processamento dos dados não teria ocorrido com sucesso se o pacote fosse recebido pelas Urls normais.

Atributos

Obrigatórios

  • msg - especifica a mensagem de erro
  • line - especifica a linha do XML original onde o erro ocorreu
  • column - especifica a coluna do XML original onde o erro ocorreu
  • pos - especifica a posição em bytes desde o inicio do XML original onde o erro ocorreu

Valores para mensagens de erro de "Error"

Os seguintes valores podem ser retornados no atributo msg de um elemento Error:

XML Depth not valid on ... O XML tem mais elementos aninhados que o previsto na definição.
Unknown element: ... O elemento descrito não é conhecido na definição XML4IPL.
Element ... can not be inside of ... . O elemento citado não pode ser usado dentro do segundo citado.
Attribute ... not allowed on element ... . O atributo - utilizado não é permitido no elemento citado.
Invalid value (...) for attribute: ... on element ... . Foi usado um valor inválido como atributo para o elemento citado.
Absent mandatory attribute: - Atributo(s) obrigatório(s) inexistente(s) no elemento citado
Sensor -: value duplication Existem duas leituras para o mesmo sensor no mesmo instante.

Exemplos

<xml4ipl ver="1.1" device="server10">
 <Response resultCode="0" message="OK"/>
 <Error msg="Attribute absent: status" line="10" column="8" pos="91">
</xml4ipl>

Warning

Tag usada para listar avisos encontrados no XML4IPL recebido. Esta tag só é retornada pelas Urls de depuração. E indica situações onde o processamento dos dados teria ocorrido com sucesso, mas situações onde alguma parte da grafia ou do comando é desnecessária.

Atributos

Obrigatórios

  • msg - especifica a mensagem de erro
  • line - especifica a linha do XML original onde o erro ocorreu, a numeração das linhas começa por 1 na linha contendo a tag raiz <xml4ipl.
  • column - especifica a coluna do XML original onde o erro ocorreu, a primeira coluna inicia em 0.
  • pos - especifica a posição em bytes desde o inicio do XML (tag xml4ipl) onde o erro ocorreu

Valores para mensagens de erro de "Warning"

Os seguintes valores podem ser retornados no atributo msg de um elemento Warning:

Attribute - redefined Existem dois valores para o mesmo atributo.
Sensor -: value redefined Sensor teve seu valor redefinido para o elemento citado.

Exemplos

 

Parâmetros de configuração de dispositivos e sensores

Os parâmetros que podem ser configurados para os dispositivos remotos e sensores usados nas tag's Property e PropertyRange são os seguintes:

  • location - informa as coordenadas geodésicas da localização do dispositivo remoto com a sua altitude em relação ao nível do mar.
  • communitacion_frequency - informa a freqüência em minutos com a qual o dispositivo remoto pretende se comunicar com a plataforma.


Estes parâmetros informam limites máximo e mínimos para os valores lidos dos sensores. Funcionam apenas para valores numéricos com limites lineares. Os dispositivos remotos que avaliarem os "status" dos sensores por este tipo de limites podem informá-los para a plataforma, e posteriormente os relatórios podem fazer uso deles para informar as razões para os "status".

  • range_normal - informa os limites que o dispositivo remoto considera normal para os valores do sensor.
  • range_warning - informa os limites considerados como valores de alerta para a operação.
  • range_critical - informa os limites considerados como valores críticos para a operação.
  • Os valores que não estiverem em nenhum dos intervalos acima será considerado Out-of-range como "status" do sensor.

Formatos como devem ser enviados os dados

Formato de envio dos valores de tempo

Os atributos que indicam valores de tempo que são o timestamp e o localtimestamp devem sempre ser enviados no seguinte formato.

Formato do valor de tempo

O valor de tempo que trafega entre os componentes via xml sempre terá o formato: AAAAMMDDhhmmss sempre definido em 24 horas.

  • Os quatro primeiros dígitos "AAAA" são para o ano. Ex: 2008
  • Os dois próximos "MM" são para o mês, de 01 para janeiro a 12 para dezembro
  • Os dois próximos "DD" são para o dia, de 01 a 31
  • Os dois próximos "hh" são para a hora em formato 24 horas, de 00 a 23 horas
  • Os dois próximos "mm" são para os minutos que vão de 00 a 59
  • Os dois próximos "ss" são para os segundos que vão de 00 a 59

Formato de envio dos valores de "unit"

A plataforma não faz qualquer crítica ao valor deste atributo. São sugeridos alguns valores para ele como forma de padronizar o uso facilitando a programação de relatórios de apresentação dos dados.

  • "%" - o valor informado é um percentual

Tabela com valores padrões para unidades de medidas:

Formato de envio dos valores de "status"

O "status" informado é avaliado pelo dispositivo remoto por seus próprios critérios. Os valores que a plataforma suporta são os seguintes:

  • OK - condição normal de operação do sensor e valor lido está dentro dos limites de normalidade.
  • WARNING - condição de atenção, valor lido fora dos limites de normalidade e fora dos limites críticos.
  • CRITICAL - condição criticas, valor lido dentro dos limites críticos.
  • ERROR - condição de erro, pode ser gerada pelo auto-teste do dispositivo remoto, ou porque o valor lido estar fora dos limites de valores possíveis.

Formato de envio do "sender_agent"

sender_agent

Atributo usado nos eventos gerados a partir dos gateways que identifica qual foi o software, firmware, etc que foi usado para fazer a conexão do dispositivo remoto com o gateway. Pode ser usado para identificar o fabricante do dispositivo ou software que está realizando a comunicação. Ele difere do nome do dispositivo pois dispositivos do mesmo fabricante com a mesma versão de firmware ou software vão obrigatoriamente ter nomes diferentes e vão ter sender_agent

Este atributo é opcional pela simples razão que nem todos os protocolos (protocol) e formatos de dados (dataformat) oferecem esta possibilidade de identificação. O xml4ipl oferece esta possibilidade.

É sugerido que dentro deste atributo venha pelo menos as seguintes informações separadas por hífen "-":

  • Nome da empresa que fabrica o equipamento ou programa
  • nome do equipamento ou programa
  • versão do programa ou do firmware do equipamento

Exemplos

Sugestão de identificação para o programa "SuperView" da empresa Novus Produtos Eletrônicos 

<xml4ipl ver="1.1" device="server10" status="OK" timestamp="20080826145756" sender_agent="novus-superview-v2.00" >

Sugestão de identificação para o programa "send_nsca_ipl" que substitui o "send_nsca" do Nagios® e transmite os dados usando o formato e protocolo do xml4ipl 

<xml4ipl ver="1.1" device="server_nsca" timestamp="20080826145756" status="OK" sender_agent="iplenix-send_nsca-v1.0" >

Formato de envio dos valores de "location"

Latitude, longitude e altitude separados por vírgula "," onde os dois primeiros são são escritos em graus decimais. O separador decimal que deve ser usado o ponto ".". A altitude deve ser enviada em metros e pode ter valor decimal separado por ponto ".".

Exemplos: 

<Property name="location" value="30.434343,55.343443,30" />


Formato de envio dos valores de "communication_frequency"

Este parâmetro informa a freqüência com a qual o dispositivo remoto pretende comunicar com a plataforma.

O valor deve ser informado por um número inteiro que representa em minutos o intervalo máximo entre as comunicações. 

<Property name="communication_frequency" value="15" />

[editar] Formato de envio dos valores de "dataformat"

Quando um outro protocolo é encapsulado usando a tag Packet o parâmetro dataformat deve ser usado para informar o formato do dado que está sendo enviado.

[editar] Valores possíveis de dataformat

  • m2mxml - antigo formato para o xml4ipl
  • xml4ipl - formato de dados padrão para a comunicação entre os dispositivos remotos e a plataforma
  • ws10 - formato de dados usado pelo equipamento WS10 da Novus Produtos Eletrônicos
  • nagios - formato usado na transmissão de dados pelo protocolo NSCA do Nagios
  • multipart-mime - formato usado na transmissão de dados de imagens

[editar] Formato de envio dos valores de "enconding"

Este parâmetro é usado no envio de dados encapsulados ou em envio de dados em formato livre. No primeiro caso ele tem que ser uma codificação conhecida pois o gateway vai decodificar o pacote para interpretá-lo. Já no segundo caso o valor vai ser armazenado pois da mesma forma será o pacote dos dados em formato livre, pois a plataforma não interpreta estes dados.

[editar] Valores possíveis para o "encoding"

  • base64

[editar] Formato de envio dos valores de "content_type"

Os valores possíveis para este parâmetro são quaisquer. Ele será simplesmente armazenado sem qualquer interpretação por parte da plataforma.